feat(finops): add bounded usage evidence authority - #315

Addresses #312 through the existing bounded usage-evidence authority lane. This remains a Draft child of dependency-root #233; protected main is not written directly.

Exact stack

• protected main: 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c at the latest verified sweep;
• exact predecessor/base test(recovery): cover stale evidence registry cleanup #233: 01d231fde23b82e2ced258d7bfcb4721ed75706d;
• hosted JSON-interoperability RED predecessor: de5cca77f556b4a2126d8e15f00aa1194e8cd75c;
• exact current repair head: 157d0ac9dcf23a54a05d010044344e0f650b8698;
• compare from exact test(recovery): cover stale evidence registry cleanup #233: 11 ahead / 0 behind, merge base exactly test(recovery): cover stale evidence registry cleanup #233;
• state: Draft/open/mergeable;
• owned relative surface remains pg_llm_batch/usage_evidence.py, tests/test_usage_evidence.py, and tests/test_usage_evidence_json_interoperability.py.

Measurement-completeness contract retained

The earlier primitive preserved provenance authority but nullable token dimensions could not losslessly distinguish measured zero from unavailable/unknown usage, nor represent partial or mixed reconciled aggregates. Test-first 040f9d9e07373f9ab9cb68ac532b0e451e0d415d established that ambiguity and production 38ecfd8ab7509ee59edc1241b5a79ab6042691fc added the pg-owned UsageCompleteness vocabulary (COMPLETE, PARTIAL, UNAVAILABLE, MIXED) and the count/completeness invariant. UNAVAILABLE requires a null count; every available state requires an explicit bounded non-negative count. Provenance remains separately owned by UsageAuthority.

That predecessor generation was repository-local GREEN, but its receipts do not transfer to later heads.

Executed JSON integer interoperability RED

Test-only de5cca77f556b4a2126d8e15f00aa1194e8cd75c added focused regressions requiring request_count, input_token_count, and output_token_count to reject 2**53 while accepting and JSON-round-tripping 2**53 - 1, with production still using _MAX_COUNT = 2**63 - 1.

That exact head produced genuine hosted RED:

• CI 35550023971: completed / failure;
• Release Acceptance 35550024233: completed / success;
• exact-head checkout and dependency setup succeeded;
• compile, Ruff, and public-docstring enforcement succeeded before the quality lane failed while executing coverage;
• Python unit lanes failed at Run unit tests on the exact source head;
• the container/PostgreSQL runtime-smoke job completed successfully.

This is source-contract RED rather than runner/queue/container failure. It proves the public canonical-JSON evidence contract still admitted integers above the cross-implementation exact-integer interoperability ceiling.

Minimum causal repair

Ordinary-forward 157d0ac9dcf23a54a05d010044344e0f650b8698 applies only the repair required by that RED:

• _MAX_COUNT narrows from 2**63 - 1 to 2**53 - 1;
• the older signed-BIGINT-maximum acceptance test is updated to require the JSON-interoperability maximum instead;
• exact built-in int admission, non-negativity, completeness invariants, deterministic canonical JSON, SHA-256 identity, bounded identifiers, and the content-minimal evidence surface are unchanged.

PostgreSQL signed BIGINT remains sufficient storage capacity; it is no longer treated as the semantic maximum of a cross-system JSON evidence contract. RFC 8259 §6 is the interoperability basis, not a claim that JSON syntax forbids larger integers.

Exact-current repository acceptance

Exact 157d0ac9dcf23a54a05d010044344e0f650b8698 has now reacquired its own repository-local evidence:

• CI 35581365862: completed / success. Exact-source verification, Python 3.10/3.12/3.14 unit lanes, container/PostgreSQL runtime smokes, compile, Ruff, public-docstring enforcement, line/branch coverage gate, lock freshness, and distribution build all completed successfully.
• Release Acceptance 35581366002: completed / success. The workflow checked out the exact PR head, materialized two clean exact-head source trees, built wheel/sdist twice, verified artifact identity, and preserved bounded release evidence.
• fresh formal reviews: none;
• fresh inline review threads: none.

This closes the branch-local JSON-interoperability RED -> minimum repair -> exact-head GREEN loop. It does not establish independent approval, protected-main integration, current central Security/SAST/model-backed acceptance, immutable release authority, or pricing/provider truth. Keep Draft.

Product / integration boundary

This slice remains evidence accounting, not pricing arithmetic, billing settlement, provider certification, or proof that reconciliation itself is correct. #318 owns future released-Contextual-Orchestrator ACL mapping and must preserve unavailable/unknown and completeness/provenance semantics rather than infer them from nullable counts or a mutable upstream enum.

After #233 reaches protected main, reconcile this child non-destructively onto the then-current protected base and reacquire every exact-final-head/current-base CI/security/SAST/coverage/docstrings/PostgreSQL/package/SBOM/provenance/release/review/thread gate required by live governance. Mutable central state belongs in #244 and live owner PRs.

Reference: Bray, T. (2017). The JavaScript Object Notation (JSON) Data Interchange Format (RFC 8259). Internet Engineering Task Force. https://doi.org/10.17487/RFC8259

No force push, destructive rebase, protected-main direct write, self-approval, gate weakening, fabricated review, mutable sibling dependency adoption, predecessor-evidence transfer, blind rerun, source-neutral wake commit, or branch-only release claim is authorized.